HAL UART I/O operations migration

This section provides information about the HAL UART I/O operations migration.

Important

The main difference between HAL1 and HAL2 in all transmit and receive functions (polling, interrupt, or DMA) is the way buffer size is specified. HAL1 uses Size for the number of data elements (u8 or u16), while HAL2 uses Size_byte to specify the buffer size in bytes, allowing more precise control.

Process polling

The following table list the HAL UART polling functions, indicating those that remain unchanged between HAL1 and HAL2:

Function

HAL1 / HAL2

Transmit 

HAL1:  HAL_UART_Transmit(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size, uint32_t Timeout)
HAL2:  HAL_UART_Transmit(hal_uart_handle_t  *huart, const void *p_data,   uint32_t size_byte, uint32_t timeout_ms)

Receive 

HAL1:  HAL_UART_Receive(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size, uint32_t Timeout)
HAL2:  HAL_UART_Receive(hal_uart_handle_t *huart, void *p_data, uint32_t size_byte, uint32_t timeout_ms)

Related use cases: Use case: UART communication in polling mode

Process IT

The following table list the HAL UART interrupt functions, indicating those that remain unchanged between HAL1 and HAL2:

Function

HAL1 / HAL2

Transmit IT 

HAL1:  HAL_UART_Transmit_IT(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_Transmit_IT(hal_uart_handle_t *huart, const void *p_data,   uint32_t size_byte)

Receive IT 

HAL1:  HAL_UART_Receive_IT(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_Receive_IT(hal_uart_handle_t *huart, void *p_data,   uint32_t size_byte)

Related use cases: Use case: UART TX in interrupt mode and Use case: UART RX in interrupt mode

Process DMA

The following table list the HAL UART DMA functions, indicating those that remain unchanged between HAL1 and HAL2:

Function

HAL1 / HAL2

Transmit DMA 

HAL1:  HAL_UART_Transmit_DMA(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_Transmit_DMA(hal_uart_handle_t *huart, const void *p_data,   uint32_t size_byte)

Receive DMA 

HAL1:  HAL_UART_Receive_DMA(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_Receive_DMA(hal_uart_handle_t *huart, void *p_data,   uint32_t size_byte)

Pause DMA 

HAL1: HAL_UART_DMAPause(UART_HandleTypeDef *huart)
HAL2: HAL_UART_Pause_DMA(hal_uart_handle_t *huart)

Resume DMA 

HAL1:  HAL_UART_DMAResume(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_Resume_DMA(hal_uart_handle_t *huart)

Related use cases: Use case: UART TX in DMA mode and Use case: UART RX in DMA mode

DMA stop

HAL1

HAL2 

HAL_UART_DMAStop(UART_HandleTypeDef *huart)

Removed in HAL2

This function’s functionality is already covered by HAL_UART_Abort_IT().

Reception to idle

The following table lists the HAL UART functions for reception to idle, indicating those that remain unchanged between HAL1 and HAL2:

Function

HAL1 / HAL2

Receive to Idle 

HAL1:  HAL_UARTEx_ReceiveToIdle(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size, uint16_t *RxLen, uint32_t Timeout)
HAL2:  HAL_UART_ReceiveToIdle  (hal_uart_handle_t *huart, void *p_data,   uint32_t size_byte, uint32_t *p_rx_size_byte, uint32_t timeout_ms)

Receive to Idle IT 

HAL1:  HAL_UARTEx_ReceiveToIdle_IT(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_ReceiveToIdle_IT  (hal_uart_handle_t *huart, void *p_data,   uint32_t size_byte)

Receive to Idle DMA 

HAL1:  HAL_UARTEx_ReceiveToIdle_DMA(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_UART_ReceiveToIdle_DMA  (hal_uart_handle_t *huart, void *p_data,   uint32_t size_byte)

Transfer abort

The following table lists the HAL UART functions for transfer abort, indicating those that remain unchanged between HAL1 and HAL2:

Function

HAL1 / HAL2

Abort 

HAL1:  HAL_UART_Abort(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_Abort(hal_uart_handle_t *huart)

Abort Transmit 

HAL1:  HAL_UART_AbortTransmit(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortTransmit(hal_uart_handle_t *huart)

Abort Receive 

HAL1:  HAL_UART_AbortReceive(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortReceive(hal_uart_handle_t *huart)

Abort IT 

HAL1:  HAL_UART_Abort_IT(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_Abort_IT(hal_uart_handle_t *huart)

Abort Transmit IT 

HAL1:  HAL_UART_AbortTransmit_IT(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortTransmit_IT(hal_uart_handle_t *huart)

Abort Receive IT 

HAL1:  HAL_UART_AbortReceive_IT(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortReceive_IT(hal_uart_handle_t *huart)

IRQ handler

Function

HAL1 / HAL2

IRQ Handler 

HAL1:  HAL_UART_IRQHandler(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_IRQHandler(hal_uart_handle_t *huart)

Register callbacks

HAL1

HAL2

In HAL1, the function HAL_UART_RegisterCallback is used to register various UART callbacks using a single function with a specific callback ID.

In HAL2, separate functions are available to register each specific UART callback, providing more granularity and control over the callback registration process. 

// Register Tx Half Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_TX_HALFCOMPLETE_CB_ID,
                          TxHalfTransferCpltCallback);

// Register Tx Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_TX_COMPLETE_CB_ID,
                          TxTransferCpltCallback);

// Register Rx Half Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_RX_HALFCOMPLETE_CB_ID,
                          RxHalfTransferCpltCallback);

// Register Rx Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_RX_COMPLETE_CB_ID,
                          RxTransferCpltCallback);

// Register Error Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_ERROR_CB_ID,
                          ErrorCallback);

// Register Abort Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_ABORT_COMPLETE_CB_ID,
                          AbortCpltCallback);

// Register Abort Transmit Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_ABORT_TRANSMIT_COMPLETE_CB_ID,
                          AbortTransmitCpltCallback);

// Register Abort Receive Complete Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_ABORT_RECEIVE_COMPLETE_CB_ID,
                          AbortReceiveCpltCallback);

// Register Wakeup Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_WAKEUP_CB_ID,
                          WakeupCallback);

// Register Rx FIFO Full Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_RX_FIFO_FULL_CB_ID,
                          RxFifoFullCallback);

// Register Tx FIFO Empty Callback
HAL_UART_RegisterCallback(&uart_handle,
                          HAL_UART_TX_FIFO_EMPTY_CB_ID,
                          TxFifoEmptyCallback);

// Register Tx Half Complete Callback
HAL_UART_RegisterTxHalfCpltCallback(&uart_handle, TxHalfTransferCpltCallback);



// Register Tx Complete Callback
HAL_UART_RegisterTxCpltCallback(&uart_handle, TxTransferCpltCallback);



// Register Rx Half Complete Callback
HAL_UART_RegisterRxHalfCpltCallback(&uart_handle, RxHalfTransferCpltCallback);



// Register Rx Complete Callback
HAL_UART_RegisterRxCpltCallback(&uart_handle, RxTransferCpltCallback);



// Register Error Callback
HAL_UART_RegisterErrorCallback(&uart_handle, ErrorCallback);



// Register Abort Complete Callback
HAL_UART_RegisterAbortCpltCallback(&uart_handle, AbortCpltCallback);



// Register Abort Transmit Complete Callback
HAL_UART_RegisterAbortTransmitCpltCallback(&uart_handle, AbortTransmitCpltCallback);



// Register Abort Receive Complete Callback
HAL_UART_RegisterAbortReceiveCpltCallback(&uart_handle, AbortReceiveCpltCallback);



// Register Wakeup Callback
HAL_UART_RegisterWakeupCallback(&uart_handle, WakeupCallback);



// Register Rx FIFO Full Callback
HAL_UART_RegisterRxFifoFullCallback(&uart_handle, RxFifoFullCallback);



// Register Tx FIFO Empty Callback
HAL_UART_RegisterTxFifoEmptyCallback(&uart_handle, TxFifoEmptyCallback);

Related concepts: Individual callback registration APIs replace global register and unregister functions

UnRegister Callbacks

In HAL2, the unregister callback API has been removed. Instead, users can manage callbacks by re-registering the default HAL UART weak callbacks as needed.

HAL1

HAL2 

// Unregister Tx Half Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_TX_HALFCOMPLETE_CB_ID);

// Unregister Tx Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_TX_COMPLETE_CB_ID);

// Unregister Rx Half Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_RX_HALFCOMPLETE_CB_ID);

// Unregister Rx Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_RX_COMPLETE_CB_ID);

// Unregister Error Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_ERROR_CB_ID);

// Unregister Abort Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_ABORT_COMPLETE_CB_ID);

// Unregister Abort Transmit Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_ABORT_TRANSMIT_COMPLETE_CB_ID);

// Unregister Abort Receive Complete Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_ABORT_RECEIVE_COMPLETE_CB_ID);

// Unregister Wakeup Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_WAKEUP_CB_ID);

// Unregister Rx FIFO Full Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_RX_FIFO_FULL_CB_ID);

// Unregister Tx FIFO Empty Callback
HAL_UART_UnRegisterCallback(&uart_handle,
                            HAL_UART_TX_FIFO_EMPTY_CB_ID);

// Re-register default Tx Half Complete Callback
HAL_UART_RegisterTxHalfCpltCallback(&uart_handle,
                                    HAL_UART_TxHalfCpltCallback);

// Re-register default Tx Complete Callback
HAL_UART_RegisterTxCpltCallback(&uart_handle,
                                HAL_UART_TxCpltCallback);

// Re-register default Rx Half Complete Callback
HAL_UART_RegisterRxHalfCpltCallback(&uart_handle,
                                    HAL_UART_RxHalfCpltCallback);

// Re-register default Rx Complete Callback
HAL_UART_RegisterRxCpltCallback(&uart_handle,
                                HAL_UART_RxCpltCallback);

// Re-register default Error Callback
HAL_UART_RegisterErrorCallback(&uart_handle,
                               HAL_UART_ErrorCallback);

// Re-register default Abort Complete Callback
HAL_UART_RegisterAbortCpltCallback(&uart_handle,
                                   HAL_UART_AbortCpltCallback);

// Re-register default Abort Transmit Complete Callback
HAL_UART_RegisterAbortTransmitCpltCallback(&uart_handle,
                                           HAL_UART_AbortTransmitCpltCallback);

// Re-register default Abort Receive Complete Callback
HAL_UART_RegisterAbortReceiveCpltCallback(&uart_handle,
                                          HAL_UART_AbortReceiveCpltCallback);

// Re-register default Wakeup Callback
HAL_UART_RegisterWakeupCallback(&uart_handle,
                                HAL_UART_WakeupCallback);

// Re-register default Rx FIFO Full Callback
HAL_UART_RegisterRxFifoFullCallback(&uart_handle,
                                    HAL_UART_RxFifoFullCallback);

// Re-register default Tx FIFO Empty Callback
HAL_UART_RegisterTxFifoEmptyCallback(&uart_handle,
                                     HAL_UART_TxFifoEmptyCallback);

Related concepts: Individual callback registration APIs replace global register and unregister functions.

Default Callbacks

The following table lists the HAL UART default callback functions, indicating those that remain unchanged between HAL1 and HAL2.

Function

HAL1 / HAL2

TX Half Complete Callback 

HAL1:  HAL_UART_TxHalfCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_TxHalfCpltCallback(hal_uart_handle_t *huart)

TX Complete Callback 

HAL1:  HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_TxCpltCallback(hal_uart_handle_t *huart)

RX Half Complete Callback 

HAL1:  HAL_UART_RxHalfCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_RxHalfCpltCallback(hal_uart_handle_t *huart)

Error Callback 

HAL1:  HAL_UART_ErrorCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_ErrorCallback(hal_uart_handle_t *huart)

Abort Complete Callback 

HAL1:  HAL_UART_AbortCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortCpltCallback(hal_uart_handle_t *huart)

Abort Transmit Complete Callback 

HAL1:  HAL_UART_AbortTransmitCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortTransmitCpltCallback(hal_uart_handle_t *huart)

Abort Receive Complete Callback 

HAL1:  HAL_UART_AbortReceiveCpltCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_AbortReceiveCpltCallback(hal_uart_handle_t *huart)

Wakeup Callback 

HAL1:  HAL_UARTEx_WakeupCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_WakeupCallback(hal_uart_handle_t *huart)

RX FIFO Full Callback 

HAL1:  HAL_UARTEx_RxFifoFullCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_RxFifoFullCallback(hal_uart_handle_t *huart)

TX FIFO Empty Callback 

HAL1:  HAL_UARTEx_TxFifoEmptyCallback(UART_HandleTypeDef *huart)
HAL2:  HAL_UART_TxFifoEmptyCallback(hal_uart_handle_t *huart)

RX complete callback

HAL1

HAL2

In HAL1, there are two separate callback functions for handling the completion of UART receive operations.

In HAL2, these have been merged into a single function with additional parameters to provide more detailed information about the receive event. 

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t Size)

void HAL_UART_RxCpltCallback(hal_uart_handle_t *huart, uint32_t size_byte,
                                hal_uart_rx_event_types_t rx_event)